Tech Arsenal 1

home *** CD-ROM | disk | FTP | other *** search

/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / seabool2.zip / SEABOOL.DOC < prev next >

Wrap

Text File | 1990-02-16 | 25KB | 658 lines

pg 1 Seabool Searcher v 1.2 (Seabool.pas) Turbo Pascal 5.0 UNIT source code. copyright 1990 by Peter Neuendorffer Documentation and Progammers Instructions. Conditional searching tool. by Peter Neuendorffer 1399 Commonwealth Ave apt. 11. Allston, MA 02134 license to use commercially: Send check for $50.00 to above address. Algorythym and additional source provided to registered user upon request. All inquiries confidential. Seabool is a Turbo Pascal 5.0 source unit. Boolean Short Circuit and Stack Checking compiler options must be enabled when compiling. files in this PROGRAMMERS package seabool.doc PRINT THIS FILE seabool.pas THE UNIT SOURCE somebool.pas A SAMPLE EXAMPLE FILE somebool.exe SAMPLE EXAMPLE FILE executable. Returns truth value of a conditon in a sentence. Bare bones example only. SERVICES: bool_init() procedure any_bool() function returns truth value of text condition informational variables are returned after call to bool_init lowercase function converts a string to lower case editstring procedure converts a string to lower case and removes leading,trailing blanks. NOTE FOLLOWING BUG FIXES IN VERSION 1.1: the bool_validation_sit code of 2 is returned if wrong syntax the bool_validation_sit code of 4 is returned if always false range test corrected in lowercase (#91 is correct number) pg 2 MANUAL introduction pg 3 how it can be used pg 5 how to use it in your program pg 6 UNIT specifications pg 7-10 pg 3 Introduction Seabool is a Turbo Pascal 5.0 source unit, effecting user specified search masks for any data or named program object. It has two procedures and provides several informational variables. This manual contains a description of how a Turbo Pascal program using the unit Seabool might appear to the user of the program. Then a general description of how seabool is used by the programmer of the program. Lastly, a reference of proper use of the two procedures, and specifications for the variables that Seabool also provides. These variables are returned to provide relevant information to the end-user-program. Care should be taken not to alter their values AT ANY time in the end-users program. These actual names should not be declared in the calling program,although their associated types may be used. They are owned by any UNIT that has "uses seabool" in the uses clause. CAUTION: do not pass to Seabool any substring types, such as string[10]. Seabool requires the string type for it's input parameters. The maximum recursion depth may need to be altered, and stack space increased, as SEABOOL is a recursive module. The recursion depth is set at the end of the seabool source file and may be altered. Because of the power of these calls, it is important that (1) the programmer understand how to use the unit. (2) that testing of a program implementing the Seabool unit be done carefully, and NOT using non-standard output devices (for example, a robot interface) for testing and/or debugging of the program. (3) during testing, all data to be searched should be copied to a temporary variable, so as to preserve integrity of data. A quick glossary so we know our terms: user: The person who will be using your Turbo Pascal program without knowledge of your source code. end-user-programmer: You: the person who writes the program implementing the Seabool unit. author: Me. The author of Seabool unit. --------------------------------------------- boolean conditon: a boolean conditon as used in this unit: Let B..Y be English words in string format. Any construct of B..Y in the following form B B and C ....and Y B or C ....or Y Not B pg 4 Seabool Introduction (continued) glossary continued: The words "and" "or" "not" are reserved words. B..Y are strings whose leading blanks and trailing blanks are ignored. Thus, actual examples of a target to be searched for might be: < Mary and (Sue or George))> <not George> <George or Mary or Sue and Ralph> <(mary and sue) or not(George and Ralph)> < Ralph >. boolean search= the presence (true) or absence (false) of a boolean condition in a programmer's search object. Thus the syntax is EXACTLY the same as an if condition (without the if) in PASCAL, C or BASIC. Parentheses may be included to stress or force order. If no parentheses the order of precedence is: NOT AND OR Thus the expression <not a and b or c> is equivalent to ((not a) and b) or c ------------------------------------------ Seabool calls: procedure bool_init(target_string); function any_bool(USER_DEFINED_PROCEDURE_NAME):boolean; note: In addition to the bool_init procedure, and the any_bool function, SEABOOL contains two other routines that it needs. These are available to the end_user programmer, but need not be called to effect a boolean search. They are the function "lowercase(str:string):string;" and the procedure "Editstring(var str:string);". Syntax and functionality for calls to these services are described at the very end of this manual. This unit is currently implemented in all Neubase SHAREWARE versions. In its present form, it is implemented in the file Neubase6.zip, which is published on The Software Connection (508)-921-4864. pg 5 Seabool Searcher:how it can be used This unit allows the end-user programmer to provide smart searching to the user of their program. An example: The user gets a database written by the end-user programmer. The end-user programmer has meanwhile retired from computers and is living on a desert island without a telephone or address. The user enters in data to his new database. This hypothetical nifty database has a query option for the user. The user may search the database for a conditon: prompt: "Search for:" user types: "this thing and (that thing or the other thing)". The database then finds all occurences in the database that satisfy the user's request. The end-user-programmer (you) need not know ANYTHING about the content of "this thing" , "that thing" or the "other thing", and in fact no longer answers his mail. Thus the user of the program can query his database data with condtions. You, the end-user programmer need not concern yourself with the content or structure of queries. A specific example: In my program Neubase6.zip, a user may enter in volumes of data in their diary. At some point they may "Search for: (phone and (mary or Sue) and not computer)" The program will find all occurences of data that mention (1) phone and (2) either mary or sue (3) but not computer. A possible example: The user issues a command to a robot. "Command (look up and walk right and not talk)" Note that the command "variables" are now not text, but actual commands from the user. A suitable example (not implemented by me): problem: search a file for a combination of topics. ex: find all files that mention "this thing and not that thing". pg 6 How to use Seabool unit in your Turbo Pascal program application. purpose: evaluate a boolean condition consisting of short text connected by "and" "or" or "not" operators with or without parentheses. The '=' , arithmetic and '>','<', and '<>' operators are not treated by Seabool, and will be considered part of the user text to be searched. The Seabool unit contains one procedure and one function, and requires a third routine from the programmer. (a) BOOL_INIT(target_string); (b) ANY_BOOL(user_defined_procedure); Calls to these two modules are made in the calling program to coordinate the search for the text condition (target_string) in the search space. (c) USER_DEFINED_PROCEDURE In addition, the enduser programmer must write a Search primitive as an interface procedure. This procedure is in specified format (see reference section below). It will provide the truth value of strings passed by Seabool. Thus the programmer need not be concerned with the complexity or order of the boolean, only whether a given text constant is "found" or not. * In the process of their search module, The end_user programmer obtains the query (target_string) from the user as a variable of type string. This is then passed to Seabool with the * call bool_init(target_string); An error code may then be returned in bool_validation_sit:byte; * If bool_validation_sit<>2 then the string is valid. * The end_user programmer goes into search loop, and during this loop * (1) obtains source string or object. * (2) passes the source string to the USER_DEFINED_PROCEDURE. (a dedicated interface variable of type string global to the USER_DEFINED_PROCEDURE would do it) * (3) evokes the function any_bool(user_defined_procedure);, where the parameter is the exact same spelling as the NAME of the USER_DEFINED_PROCEDURE. * (4) the truth value of the target_string in the source_string has been returned as a true or false in the any_bool function. pg 7 Seabool.pas UNIT specifations Specifications of all Seabool procedures, functions and variables that are to be used by the end-user-programmer. _____________________________________________________________ * procedure BOOL_INIT(target_string); this initilizes the Seabool search by passing the target_string that contains the boolean condition to be found. This is called AFTER the target_string is obtained and BEFORE going into your search loop.It should be called only once for any given target_string. Seabool may slightly simplify the target_string after a call to bool_init, but will be functionally identical in lower case to the target_string before the call. After calling bool_init, associated information is provided to the programmer, which is described in detail in the reference section of this manual. The end-user-programmer must check bool_validation_sit byte type variable to see that it is not equal to 2 {invalid target string} _____________________________________________________________ * variable: bool_validation_sit: byte; possible values. 100 not initialized ever 1 boolean is acceptable 2 boolean is incorrect in syntax or too complicated. 4 boolean is logically always false * function ANY_BOOL(USER_DEFINED_PROCEDURE_NAME):boolean; user_defined_procedure_name must correspond exactly to the name of the user_defined_procedure written by the programmer. Note their may be several such procedures. The one the programmer chooses is declared to Seabool based on the parameter used in the evokation of the any_bool function. If bool_validation_sit IS 2 or 4 AFTER calling bool_init, indicating an invalid or "always false" target_string,than the results of bool should always be false. Bool is a function. It returns TRUE if the conditon named in the last bool_init(target_string) is present in the last interface_source_string passed to the USER_DEFINED PROCEDURE. thus if source_string contains "The rain in Spain", and the user target string is '(rain or Spain)' after the code <interface_source_string:=source_string; result:=any_bool(user_defined_procedure);> the result variable would contain boolean TRUE. * NOTE ANYBOOL does not deal with leading,trailing blanks, and is NOT CASE SENSITIVE. pg 8 Seabool UNIT specifications (cont) _____________________________________________________________ * USER_DEFINED_PROCEDURE. This is a search primitive the END-USER- PROGRAMMER WRITES. It may be declared in the interface of your search routine file. A FAR call {$F+} compiler option must be invoked for this procedure. (see Turbo Pascal manual for your version 4.0 to 5.5 for details on F+ compiler option) It must be in the following format, although the names of the variables may be the programmer's choice: {$F+} user_defined_procedure(var seabool_target:string; var found:boolean); {$F-}. The variable seabool_target must NEVER be altered by the end-user programmer. It is provided by Seabool unit. The procedure must return true or false in "found" variable. The routine will be fed various text variables by Seabool, which may be one or more of the text objects specified in the original target string passed to bool_init. The programmer is expected to say whether each text is "found" in the source being searched. The source string or object may be passed to the procedure using an interface variable dedicated to this purpose. _____________________________________________________________ VARIABLES returned after valid call to bool_init (where bool_validation_sit <> 2 type {note} letter_type: 'a'..#123;{sublist of char} If bool_validation_sit is NOT 2, then the following variables are defined: _____________________________________________________________ variable name: length_object_hash_table_0:letter_type; meaning: number of distinct variables in user boolean. counter relative to 'b'. Thus a value of 'c' indicates two variables were present. variable indexes 'b' to 'y' are supported. Thus your user string may contain up to 24 variables. Any more will return an error code of 2 in bool_validation_sit after a call to bool_init. pg 9 Seabool UNIT specifications (cont) _____________________________________________________________ variable name: search_object_hash_table_0 : array [letter_type] of string; meaning: The list of variable values in target_string. thus user_hash_table['b'] contains the first variable etc. Note the indexes of this array are indexed with letters starting with 'b'. If for example, the target_ string from the user was <phone and (mary or not sue)>, then the array would be filled after bool_init(target_string); with search_object_hash_table_0['b']='phone'; search_object_hash_table_0['c']='mary'; search_object_hash_table_0['d']='sue'; You need not examine this array to effect the boolean search, but the information is provided. Note all text will be with no leading blanks or trailing blanks, and will be in lower case. _____________________________________________________________ variable name: bool_crit_true : array['a'..#123] of boolean; meaning: one to one correspondence to user_hash_table by index. If true, then the associated variable is CRITICAL to the truth value of the boolean. thus is bool_crit_true['b'] is true, then the first variable in the user_hash_table array MUST be true for the expression to be true. In the above example, after a call to bool_init('phone and (mary or not sue)'); the array would contain bool_crit_true['b']=true bool_crit_true['c']=false bool_crit_true['d']=false Once again, this array need not be referenced to effect a boolean search with bool function. _____________________________________________________________ variable name: max_bool_recursion_depth: byte; meaning: measure of maximum recursion allowed. Every call to the interenal parser increments a counter. If this counter exceeds the max_bool_recursion_depth, then bool_init returns a 2 in bool_validation_sit. No other variables returned will be defined. Max_bool_recursion_depth has been set to 24 in the Initialization of the Seabool unit {at the end of the source file}. If altered, this number should be hard coded in the Seabool source. pg 10 Seabool UNIT specifications (cont) _____________________________________________________________ variable name: and_op,or_op :boolean; After a call to bool_init, the values of and_op, or_op have the following meanings: and_op=true or_op=true meaning ___________ __________ _______ yes yes If operators in target_string, then only AND operator present. no yes If operators in target_string, then only OR operator present. no no If operators in target string, the NOT operator is present. _____________________________________________________________ Once again, these variables need not be examined by the end-user programmer to effect a boolean search using bool and bool_init. * Other services provided by Seabool: {routines used by Seabool, that need not be used by the end user programmer, but are independently available} function lowercase(str:string):string; Function returns the string "str" in lowercase without affecting non-alphabetic characters. procedure Editstring(var str:string); Converts a string "str" to lowercase and removes any leading or trailing blanks from the string. NOTE, IF YOU USE THESE TWO SERVICES TO SUPPORT ANY STRING TYPE THAT IS OF NOT TYPE string, SEABOOL must be compiled with the relaxed string checking compiler option enabled. {see Turbo Pascal manual, or THE COMPLETE TURBO PASCAL REFERENCE by Stephen K. O'brien). * QUICK REFERENCE: define search primitive obtain target_string call bool_init(target_string) examine bool_validation_sit 2 means bad 4 means always false pass each source string to a variable available to your search primitive call result:=any_bool(search primitive name); result will be true if target_string condition is satisfied in source string, false if not.